using System.Collections.Generic;

using lucere.io;

namespace lucere.index
{
    /// <summary>
    /// Expert: represents a single commit into an index as seen by the 
    /// IIndexDeletionPolicy or IIndexReader.
    /// <para>
    /// Changes to the content of an index are made visible only after 
    /// the writer who made that change commits by writing a new segments 
    /// file segments_N. This point in time, when the action of writing 
    /// of a new segments file to the directory is completed, is an index commit.
    /// </para>
    /// <para>
    /// Each index commit point has a unique segments file associated with it. 
    /// The segments file associated with a later index commit point would have 
    /// a larger N.
    /// </para>
    /// </summary>
    public interface IIndexCommit
    {
        /// <summary>
        /// Get the segments file (<code>segments_N</code>) associated with this commit point.
        /// </summary>
        string SegmentsFilename { get; } 

        /// <summary>
        /// Returns all index files referenced by this commit point.
        /// </summary>
        IList<string> Filenames { get; } 

        /// <summary>
        /// Returns the Directory for the index.
        /// </summary>
        /// <returns></returns>
        IDirectory Directory { get; }

        /// <summary>
        /// Delete this commit point.  This only applies when using
        /// the commit point in the context of IndexWriter's
        /// IndexDeletionPolicy.
        /// <para>
        /// Upon calling this, the writer is notified that this commit 
        /// point should be deleted. 
        /// </para>
        /// <para>Decision that a commit-point should be deleted is taken 
        /// by the IIndexDeletionPolicy in effect and therefore this should 
        /// only be called by its IIndexDeletionPolicy.OnInit() or 
        /// IndexDeletionPolicy.OnCommit methods.
        /// </para>
        /// </summary>
        void Delete();

        bool IsDeleted { get; }

        /// <summary>
        /// Returns true if this commit is an optimized index.
        /// </summary>
        bool IsOptimized { get; } 


        /// <summary>
        /// Returns the version for this IndexCommit.  This is the same value 
        /// that IIndexReader.Version would return if it were opened on this commit.
        /// </summary>
        long Version { get; } 
        
        /// <summary>
        /// Returns the generation (the _N in segments_N) for this  IndexCommit 
        /// </summary>
        /// <returns></returns>
        long Generation { get; }

  
        /// <summary>
        /// Convenience property that returns the last modified time of the 
        /// segments_N file corresponding to this index commit, equivalent to 
        /// IDirectory.FileModified(SegmentsFileName)
        /// </summary>
        /// <returns></returns>
        long Timestamp { get; } 

        /// <summary>
        /// Returns userData, previously passed to
        /// IndexWriter.Commit(IDictionary<string, string>) for this commit.  
        /// </summary>
        /// <returns></returns>
        IDictionary<string, string> UserData { get; }
    }
}